package cn.song.freight.service;

import cn.song.freight.domain.dto.*;
import cn.song.freight.domain.entity.AreaDO;
import cn.song.freight.domain.result.PageUtils;
import com.baomidou.mybatisplus.extension.service.IService;
import java.util.List;

/**
 * 区域服务接口
 * <pre>
 * 该服务实现提供物流系统的区域管理功能，支持区域的增删改查操作，
 * 并提供区域树形结构的构建功能，用于前端展示层级化的区域信息。
 *
 * 核心功能：
 * - 区域信息的添加、删除、更新和查询
 * - 支持多条件组合查询
 * - 提供树形结构的区域数据组织方式
 * - 数据完整性校验和业务规则验证
 *
 * 区域层级说明：
 * 1. 省级区域（level=1）：包含省份编码和名称
 * 2. 市级区域（level=2）：包含城市编码和名称，关联省级区域
 * 3. 区县级区域（level=3）：包含区县编码和名称，关联市级区域
 *
 * @author SongRenShuo
 * @version 3.0.0
 * @since 2025-08-23

 */
public interface AreaService extends IService<AreaDO> {

    /**
     * 添加新的区域信息
     * <pre>
     * 该方法实现区域信息的添加功能，会对组合字段的唯一性进行校验，
     * 确保同一组合（省份编码+城市编码+区县编码+层级）不会重复添加，保证数据的完整性。
     * 同时根据层级动态校验对应的必填字段。
     *
     * @param addDTO 区域添加数据传输对象，包含区域的基本信息
     * @return 添加结果，true表示添加成功，false表示添加失败
     * @throws IllegalArgumentException 如果数据校验失败或组合字段已存在
     */
    Boolean addArea(AreaAddDTO addDTO);

    /**
     * 删除指定的区域信息
     * <pre>
     * 该方法实现区域信息的删除功能，会先校验区域是否存在，
     * 并检查该区域是否已被运费策略绑定使用，避免误删正在使用的区域数据。
     *
     * @param deleteDTO 区域删除数据传输对象，包含要删除的区域ID
     * @return 删除结果，true表示删除成功，false表示删除失败
     * @throws IllegalArgumentException 如果区域不存在或已被策略绑定使用
     */
    Boolean deleteArea(AreaDeleteDTO deleteDTO);

    /**
     * 更新区域信息
     * <pre>
     * 该方法实现区域信息的更新功能，会先校验区域是否存在，
     * 然后根据传入的更新数据对区域信息进行更新操作。
     *
     * @param updateDTO 区域更新数据传输对象，包含要更新的区域ID和新信息
     * @return 更新结果，true表示更新成功，false表示更新失败
     * @throws IllegalArgumentException 如果区域不存在
     */
    Boolean updateArea(AreaUpdateDTO updateDTO);

    /**
     * 查询区域列表（分页）
     * <pre>
     * 该方法实现区域信息的条件查询功能，支持按编码、名称和层级进行查询，
     * 查询结果按层级和编码进行排序，便于展示和处理。支持分页查询。
     *
     * @param queryDTO 区域查询数据传输对象，包含查询条件和分页参数
     * @return 分页的区域列表
     */
    PageUtils<AreaDO> listAreas(AreaQueryDTO queryDTO);

    /**
     * 查询区域列表（兼容性接口，返回所有数据）
     * <pre>
     * 该方法保持与原有接口的兼容性，返回所有符合条件的数据，不进行分页。
     *
     * @param queryDTO 区域查询数据传输对象，包含查询条件
     * @return 所有符合条件的区域列表
     */
    List<AreaDO> listAreasForCompatibility(AreaQueryDTO queryDTO);

    /**
     * 查询区域树形结构列表
     * <pre>
     * 该方法实现区域信息的树形结构查询功能，先获取符合条件的区域列表，
     * 然后将其构建成树形结构，便于前端进行层级展示。
     *
     * @param queryDTO 区域查询数据传输对象，包含查询条件
     * @return 树形结构的区域列表
     */
    List<AreaTreeDTO> listAreasTree(AreaQueryDTO queryDTO);

    /**
     * 导出区域数据为Excel文件
     * <pre>
     * 该方法实现区域数据的导出功能，根据查询条件获取区域数据，
     * 然后生成Excel格式的文件数据。支持所有查询条件的过滤。
     * 使用 FastExcel 进行高性能 Excel 文件生成。
     *
     * @param queryDTO 区域查询数据传输对象，包含查询条件
     * @return Excel文件的字节数组
     */
    byte[] exportAreasToExcel(AreaQueryDTO queryDTO);
}
